\doxysection{x\+Semaphore\+Create\+Recursive\+Mutex\+Static }
\hypertarget{group__x_semaphore_create_recursive_mutex_static}{}\label{group__x_semaphore_create_recursive_mutex_static}\index{xSemaphoreCreateRecursiveMutexStatic@{xSemaphoreCreateRecursiveMutexStatic}}
semphr. h 
\begin{DoxyPre}SemaphoreHandle\_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore\_t *pxMutexBuffer )\end{DoxyPre}


Creates a new recursive mutex type semaphore instance, and returns a handle by which the new recursive mutex can be referenced.

Internally, within the Free\+RTOS implementation, recursive mutexs use a block of memory, in which the mutex structure is stored. If a recursive mutex is created using x\+Semaphore\+Create\+Recursive\+Mutex() then the required memory is automatically dynamically allocated inside the x\+Semaphore\+Create\+Recursive\+Mutex() function. (see \href{http://www.freertos.org/a00111.html}{\texttt{http\+://www.\+freertos.\+org/a00111.\+html}}). If a recursive mutex is created using x\+Semaphore\+Create\+Recursive\+Mutex\+Static() then the application writer must provide the memory that will get used by the mutex. x\+Semaphore\+Create\+Recursive\+Mutex\+Static() therefore allows a recursive mutex to be created without using any dynamic memory allocation.

Mutexes created using this macro can be accessed using the x\+Semaphore\+Take\+Recursive() and x\+Semaphore\+Give\+Recursive() macros. The x\+Semaphore\+Take() and x\+Semaphore\+Give() macros must not be used.

A mutex used recursively can be \textquotesingle{}taken\textquotesingle{} repeatedly by the owner. The mutex doesn\textquotesingle{}t become available again until the owner has called x\+Semaphore\+Give\+Recursive() for each successful \textquotesingle{}take\textquotesingle{} request. For example, if a task successfully \textquotesingle{}takes\textquotesingle{} the same mutex 5 times then the mutex will not be available to any other task until it has also \textquotesingle{}given\textquotesingle{} the mutex back exactly five times.

This type of semaphore uses a priority inheritance mechanism so a task \textquotesingle{}taking\textquotesingle{} a semaphore MUST ALWAYS \textquotesingle{}give\textquotesingle{} the semaphore back once the semaphore it is no longer required.

Mutex type semaphores cannot be used from within interrupt service routines.

See x\+Semaphore\+Create\+Binary() for an alternative implementation that can be used for pure synchronisation (where one task or interrupt always \textquotesingle{}gives\textquotesingle{} the semaphore and another always \textquotesingle{}takes\textquotesingle{} the semaphore) and from within interrupt service routines.


\begin{DoxyParams}{Parameters}
{\em px\+Mutex\+Buffer} & Must point to a variable of type Static\+Semaphore\+\_\+t, which will then be used to hold the recursive mutex\textquotesingle{}s data structure, removing the need for the memory to be allocated dynamically.\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
If the recursive mutex was successfully created then a handle to the created recursive mutex is returned. If px\+Mutex\+Buffer was NULL then NULL is returned.
\end{DoxyReturn}
Example usage\+: 
\begin{DoxyPre}
SemaphoreHandle\_t xSemaphore;
StaticSemaphore\_t xMutexBuffer;

void vATask( void * pvParameters )
\{
   // A recursive semaphore cannot be used before it is created.  Here a
   // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().
   // The address of xMutexBuffer is passed into the function, and will hold
   // the mutexes data structures -\/ so no dynamic memory allocation will be
   // attempted.
   xSemaphore = xSemaphoreCreateRecursiveMutexStatic( \&xMutexBuffer );

   // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
   // so there is no need to check it.
\}
\end{DoxyPre}
 